StayAwake 1.0 — VoiceOver User Guide
======================================
A free menubar utility for blind Mac users.
Built by a blind Mac user, for blind Mac users.
VO = VoiceOver modifier key (Caps Lock, or Control+Option)


WHAT STAYAWAKE DOES
--------------------
StayAwake sits silently in your menubar and does two things:

  1. Keeps your Mac fully awake — no sleep, ever — for as long
     as you need, without any instruction from you.
  2. Returns your Mac to normal sleep behaviour instantly,
     the moment you ask it to.

No window. No Dock icon. No fuss.
VoiceOver announces every state change automatically.
It will never cause your Mac to freeze or VoiceOver to go silent.


REQUIREMENTS
------------
  - macOS 13 Ventura or later
  - Apple Silicon or Intel Mac


================================================================
STEP 1: INSTALL STAYAWAKE
================================================================

Step 1.1 — Unzip the file
  - Find StayAwake.zip wherever you saved it.
  - Double-click it or press Command+Down Arrow on it.
  - StayAwake.app appears next to the zip.

Step 1.2 — Move to Applications
  - Select StayAwake.app and press Command+C to copy.
  - Press Command+Shift+A to open your Applications folder.
  - Press Command+V to paste.
  - StayAwake is now installed.


================================================================
STEP 2: FIRST LAUNCH AND SECURITY APPROVAL (one time only)
================================================================

Because StayAwake is not from the Mac App Store, macOS will
block it the very first time. This is normal and takes about
one minute to fix.

Step 2.1 — Try to open it
  - In Applications, navigate to StayAwake.app.
  - Press Command+Down Arrow or VO+Space to open it.
  - macOS shows a dialog saying it cannot verify the developer.
  - Navigate to the "Done" button and press VO+Space.
    Do NOT press "Move to Trash."

Step 2.2 — Approve it in System Settings
  - Press Command+Space, type: System Settings, press Return.
  - Press VO+F3 to open window spots.
  - Navigate to "Privacy & Security" and press VO+Space.
  - Navigate with VO+Right Arrow until you hear:
      "'StayAwake' was blocked from use because it is not
      from an identified developer."
  - Just below that is an "Open Anyway" button.
  - Press VO+Space on "Open Anyway."
  - A confirmation dialog appears. Navigate to "Open" and
    press VO+Space.

Step 2.3 — StayAwake is now running
  - It launches silently into your menubar.
  - No window appears. No Dock icon. That is correct.
  - This approval is permanent. You never do it again.


================================================================
STEP 3: USING STAYAWAKE EVERY DAY
================================================================

--- KEEP YOUR MAC AWAKE ---

  1. Press VO+M+M to reach the menubar extras area.
     (Press M twice after your VO modifier.)
  2. Navigate with VO+Right Arrow until you hear:
       "StayAwake status: sleep allowed. Activate to open menu."
  3. Press VO+Space to open the menu.
  4. Navigate to "Keep Mac Awake" and press VO+Space.
     Or simply press the letter K.
  5. VoiceOver announces:
       "Mac will now stay awake. Sleep is prevented."
  Done. Your Mac will not sleep until you say so.


--- RETURN MAC TO NORMAL SLEEP ---

  1. Press VO+M+M to reach the menubar extras area.
  2. Navigate to StayAwake — you will hear:
       "StayAwake status: sleep prevented. Activate to open menu."
  3. Press VO+Space to open the menu.
  4. Navigate to "Allow Sleep (return to normal)" and press VO+Space.
     Or simply press the letter S.
  5. VoiceOver announces:
       "Mac returned to normal. Sleep is now allowed."
  Done. Normal sleep behaviour restored immediately.


--- QUIT STAYAWAKE ---

  - Open the StayAwake menu and navigate to "Quit StayAwake."
  - Press VO+Space. Or press Q.
  - The app exits cleanly. Sleep is automatically restored.


================================================================
KEYBOARD SHORTCUTS (while StayAwake menu is open)
================================================================

  K        Keep Mac Awake
  S        Allow Sleep (return to normal)
  Q        Quit StayAwake
  Escape   Close menu without doing anything


================================================================
OPTIONAL: LAUNCH STAYAWAKE AT LOGIN AUTOMATICALLY
================================================================

Do this if you want StayAwake ready in your menubar every time
your Mac starts, without having to launch it manually.

  1. Press Command+Space, type: System Settings, press Return.
  2. Press VO+F3, navigate to "General" and activate it.
  3. Navigate to "Login Items & Extensions" and activate it.
  4. Find the Add button (plus sign) and activate it.
  5. A file chooser opens. Navigate to Applications,
     then to StayAwake.app, and press Return.
  6. StayAwake now appears in your Login Items list.

From now on it launches silently at every login.
Note: it will NOT keep your Mac awake automatically —
you still choose when to activate it each time.


================================================================
TROUBLESHOOTING
================================================================

"I cannot find StayAwake in the menubar"
  - Make sure it is running. Press Command+Space, type StayAwake,
    press Return to launch it.
  - Use VO+M+M (M pressed twice), not VO+M (once).
    On modern macOS, third-party menubar apps live in the
    extras area reached with the double M press.

"VoiceOver did not announce the state change"
  - Wait 1 to 2 seconds after activating the menu item.
    The announcement is slightly delayed on purpose to avoid
    clashing with the menu close sound.
  - Check VoiceOver Utility > Verbosity > Announcements and
    make sure the priority level is set to medium or high.

"macOS says the app is damaged or can't be opened"
  - Open Terminal (Command+Space, type Terminal, press Return).
  - Type this exactly and press Return:
      xattr -cr ~/Applications/StayAwake.app
  - Then try launching StayAwake again.


================================================================
HOW IT WORKS
================================================================

StayAwake uses Apple's built-in caffeinate command, which has
been part of macOS since Mountain Lion. Caffeinate runs on a
background thread completely separate from the user interface,
which is why VoiceOver can never freeze or go silent while
StayAwake is running.

When keeping awake it prevents display sleep, system idle sleep,
and disk sleep all at once. When you choose Allow Sleep it is
terminated cleanly and your Mac returns to normal within seconds.
No restart ever needed.


================================================================
StayAwake 1.0
Free to use and share.
Built by a blind Mac user, for blind Mac users.
================================================================
